Python FastAPI Obsługa błędów: Tworzenie solidnych niestandardowych obsługi wyjątków

Obsługa błędów to kluczowy aspekt tworzenia solidnych i niezawodnych API. W FastAPI dla Pythona możesz wykorzystać niestandardowe obsługi wyjątków, aby elegancko zarządzać błędami i dostarczać klientom informacyjne odpowiedzi. Ten wpis na blogu przeprowadzi Cię przez proces tworzenia niestandardowych obsługi wyjątków w FastAPI, umożliwiając budowanie bardziej odpornych i przyjaznych dla użytkownika aplikacji.

Dlaczego niestandardowe obsługi wyjątków?

FastAPI zapewnia wbudowane wsparcie dla obsługi wyjątków. Jednak poleganie wyłącznie na domyślnych odpowiedziach na błędy może pozostawić klientów z niejasnymi lub mało pomocnymi informacjami. Niestandardowe obsługi wyjątków oferują kilka zalet:

\n
• Poprawione doświadczenie użytkownika: Dostarczaj jasne i informacyjne komunikaty o błędach, dostosowane do konkretnych scenariuszy błędów.
\n
• Scentralizowane zarządzanie błędami: Skonsoliduj logikę obsługi błędów w jednym miejscu, dzięki czemu Twój kod będzie łatwiejszy w utrzymaniu.
\n
• Spójne odpowiedzi na błędy: Upewnij się, że odpowiedzi na błędy mają spójny format, poprawiając użyteczność API.
\n
• Zwiększone bezpieczeństwo: Zapobiegaj ujawnianiu wrażliwych informacji w komunikatach o błędach.
\n
• Niestandardowe logowanie: Loguj szczegółowe informacje o błędach w celach debugowania i monitorowania.
\n

Zrozumienie obsługi wyjątków w FastAPI

FastAPI wykorzystuje połączenie wbudowanych w Pythona mechanizmów obsługi wyjątków i własnego systemu wstrzykiwania zależności do zarządzania błędami. Gdy wyjątek zostanie zgłoszony w ramach ścieżki (route) lub zależności, FastAPI wyszukuje odpowiedni obsługę wyjątków, aby go przetworzyć.

Obsługi wyjątków to funkcje udekorowane @app.exception_handler(), które przyjmują dwa argumenty: typ wyjątku i obiekt żądania. Obsługa jest odpowiedzialna za zwrócenie odpowiedniej odpowiedzi HTTP.

Tworzenie niestandardowych wyjątków

Przed zdefiniowaniem niestandardowych obsługi wyjątków często warto stworzyć niestandardowe klasy wyjątków, które reprezentują specyficzne warunki błędów w Twojej aplikacji. Poprawia to czytelność kodu i ułatwia obsługę różnych typów błędów.

Na przykład, załóżmy, że budujesz API e-commerce i musisz obsłużyć przypadki, gdy produkt jest niedostępny w magazynie. Możesz zdefiniować niestandardową klasę wyjątku o nazwie OutOfStockError:

            \nclass OutOfStockError(Exception):\n    def __init__(self, product_id: int):\n        self.product_id = product_id\n        self.message = f"Product with ID {product_id} is out of stock."\n
            

              
                Copy
              
            
          

Ta niestandardowa klasa wyjątku dziedziczy po bazowej klasie Exception i zawiera atrybut product_id oraz niestandardowy komunikat o błędzie.

Implementacja niestandardowych obsługi wyjątków

Teraz utwórzmy niestandardowy obsługę wyjątków dla OutOfStockError. Ten obsługę przechwyci wyjątek i zwróci odpowiedź HTTP 400 (Bad Request) z treścią JSON zawierającą komunikat o błędzie.

            \nfrom fastapi import FastAPI, Request, HTTPException\nfrom fastapi.responses import JSONResponse\n\napp = FastAPI()\n\nclass OutOfStockError(Exception):\n    def __init__(self, product_id: int):\n        self.product_id = product_id\n        self.message = f"Product with ID {product_id} is out of stock."\n\n@app.exception_handler(OutOfStockError)\nasync def out_of_stock_exception_handler(request: Request, exc: OutOfStockError):\n    return JSONResponse(\n        status_code=400,\n        content={\"message\": exc.message},\n    )\n\n@app.get(\"/products/{product_id}\")\nasync def get_product(product_id: int):\n    # Simulate checking product stock\n    if product_id == 123:\n        raise OutOfStockError(product_id=product_id)\n    return {\"product_id\": product_id, \"name\": \"Example Product\", \"price\": 29.99}\n
            

              
                Copy
              
            
          

W tym przykładzie dekorator @app.exception_handler(OutOfStockError) rejestruje funkcję out_of_stock_exception_handler do obsługi wyjątków OutOfStockError. Gdy wyjątek OutOfStockError zostanie zgłoszony w ścieżce get_product, wywoływana jest obsługa wyjątków. Obsługa zwraca następnie JSONResponse ze statusem 400 i treścią JSON zawierającą komunikat o błędzie.

Obsługa wielu typów wyjątków

Możesz zdefiniować wiele obsługi wyjątków do obsługi różnych typów wyjątków. Na przykład, możesz chcieć obsłużyć wyjątki ValueError, które występują podczas parsowania danych wejściowych użytkownika.

            \nfrom fastapi import FastAPI, Request\nfrom fastapi.responses import JSONResponse\n\napp = FastAPI()\n\n@app.exception_handler(ValueError)\nasync def value_error_exception_handler(request: Request, exc: ValueError):\n    return JSONResponse(\n        status_code=400,\n        content={\"message\": str(exc)},\n    )\n\n@app.get(\"/items/{item_id}\")\nasync def get_item(item_id: int):\n    # Simulate invalid item_id\n    if item_id < 0:\n        raise ValueError("Item ID must be a positive integer.")\n    return {\"item_id\": item_id, \"name\": \"Example Item\"}\n
            

              
                Copy
              
            
          

W tym przykładzie funkcja value_error_exception_handler obsługuje wyjątki ValueError. Wyodrębnia komunikat o błędzie z obiektu wyjątku i zwraca go w odpowiedzi JSON.

Używanie HTTPException

FastAPI udostępnia wbudowaną klasę wyjątku o nazwie HTTPException, która może być używana do zgłaszania błędów specyficznych dla HTTP. Może to być przydatne do obsługi typowych scenariuszy błędów, takich jak nieautoryzowany dostęp lub brak zasobu.

            \nfrom fastapi import FastAPI, HTTPException\n\napp = FastAPI()\n\n@app.get(\"/users/{user_id}\")\nasync def get_user(user_id: int):\n    # Simulate user not found\n    if user_id == 999:\n        raise HTTPException(status_code=404, detail="User not found")\n    return {\"user_id\": user_id, \"name\": \"Example User\"}\n
            

              
                Copy
              
            
          

W tym przykładzie wyjątek HTTPException jest zgłaszany ze statusem 404 (Not Found) i komunikatem szczegółowym. FastAPI automatycznie obsługuje wyjątki HTTPException i zwraca odpowiedź JSON z określonym statusem i komunikatem szczegółowym.

Globalne obsługi wyjątków

Możesz również zdefiniować globalne obsługi wyjątków, które przechwytują wszystkie nieobsłużone wyjątki. Może to być przydatne do logowania błędów lub zwracania ogólnego komunikatu o błędzie do klienta.

            \nfrom fastapi import FastAPI, Request\nfrom fastapi.responses import JSONResponse\nimport logging\n\napp = FastAPI()\n\nlogger = logging.getLogger(__name__)\n\n@app.exception_handler(Exception)\nasync def global_exception_handler(request: Request, exc: Exception):\n    logger.exception(f"Unhandled exception: {exc}")\n    return JSONResponse(\n        status_code=500,\n        content={\"message\": \"Internal server error\"},\n    )\n\n@app.get(\"/error\")\nasync def trigger_error():\n    raise ValueError("This is a test error.")\n
            

              
                Copy
              
            
          

W tym przykładzie funkcja global_exception_handler obsługuje wszystkie wyjątki, które nie są obsługiwane przez inne obsługi wyjątków. Loguje błąd i zwraca odpowiedź 500 (Internal Server Error) z ogólnym komunikatem o błędzie.

Używanie oprogramowania pośredniczącego (Middleware) do obsługi wyjątków

Innym podejściem do obsługi wyjątków jest użycie oprogramowania pośredniczącego (middleware). Funkcje middleware są wykonywane przed i po każdym żądaniu, umożliwiając przechwytywanie i obsługę wyjątków na wyższym poziomie. Może to być przydatne do zadań takich jak logowanie żądań i odpowiedzi, lub do implementacji niestandardowej logiki uwierzytelniania lub autoryzacji.

            \nfrom fastapi import FastAPI, Request\nfrom fastapi.responses import JSONResponse\nimport logging\n\napp = FastAPI()\n\nlogger = logging.getLogger(__name__)\n\n@app.middleware("http")\nasync def exception_middleware(request: Request, call_next):\n    try:\n        response = await call_next(request)\n    except Exception as exc:\n        logger.exception(f"Unhandled exception: {exc}")\n        return JSONResponse(\n            status_code=500,\n            content={\"message\": \"Internal server error\"},\n        )\n    return response\n\n@app.get(\"/error\")\nasync def trigger_error():\n    raise ValueError("This is a test error.")\n
            

              
                Copy
              
            
          

W tym przykładzie funkcja exception_middleware otacza logikę przetwarzania żądania blokiem try...except. Jeśli wyjątek zostanie zgłoszony podczas przetwarzania żądania, middleware loguje błąd i zwraca odpowiedź 500 (Internal Server Error).

Przykład: Internacjonalizacja (i18n) i komunikaty o błędach

Podczas tworzenia API dla globalnej publiczności, rozważ internacjonalizację komunikatów o błędach. Wiąże się to z dostarczaniem komunikatów o błędach w różnych językach, w zależności od ustawień regionalnych użytkownika. Chociaż pełna implementacja i18n wykracza poza zakres tego artykułu, oto uproszczony przykład demonstrujący tę koncepcję:

            \nfrom fastapi import FastAPI, Request, HTTPException\nfrom fastapi.responses import JSONResponse\nfrom typing import Dict\n\napp = FastAPI()\n\n# Mock translation dictionary (replace with a real i18n library)\ntranslations: Dict[str, Dict[str, str]] = {\n    \"en\": {\n        \"product_not_found\": \"Product with ID {product_id} not found.\",\n        \"invalid_input\": \"Invalid input: {error_message}\",\n    },\n    \"fr\": {\n        \"product_not_found\": \"Produit avec l'ID {product_id} introuvable.\",\n        \"invalid_input\": \"Entrée invalide\u00a0: {error_message}\",\n    },\n    \"es\": {\n        \"product_not_found\": \"Producto con ID {product_id} no encontrado.\",\n        \"invalid_input\": \"Entrada inválida: {error_message}\",\n    },\n    \"de\": {\n        \"product_not_found\": \"Produkt mit ID {product_id} nicht gefunden.\",\n        \"invalid_input\": \"Ungültige Eingabe: {error_message}\",\n    }\n}\n\ndef get_translation(locale: str, key: str, **kwargs) -> str:\n    \"\"\"Retrieves a translation for a given locale and key.\n    If the locale or key is not found, returns a default message.\n    \"\"\"\n    if locale in translations and key in translations[locale]:\n        return translations[locale][key].format(**kwargs)\n    return f\"Translation missing for key '{key}' in locale '{locale}'.\"\n\n@app.get(\"/products/{product_id}\")\nasync def get_product(request: Request, product_id: int, locale: str = \"en\"):\n    # Simulate product lookup\n    if product_id > 100:\n        message = get_translation(locale, \"product_not_found\", product_id=product_id)\n        raise HTTPException(status_code=404, detail=message)\n\n    if product_id < 0:\n         message = get_translation(locale, \"invalid_input\", error_message=\"Product ID must be positive\")\n         raise HTTPException(status_code=400, detail=message)\n\n    return {\"product_id\": product_id, \"name\": \"Example Product\"}\n
            

              
                Copy
              
            
          

Kluczowe ulepszenia dla przykładu i18n:

\n
• Parametr lokalizacji: Ścieżka akceptuje teraz parametr zapytania locale, umożliwiając klientom określenie preferowanego języka (domyślnie "en" dla angielskiego).
\n
• Słownik tłumaczeń: Słownik translations (mock) przechowuje komunikaty o błędach dla różnych lokalizacji (w tym przypadku angielski, francuski, hiszpański, niemiecki). W prawdziwej aplikacji użyłbyś dedykowanej biblioteki i18n.
\n
• Funkcja get_translation: Ta pomocnicza funkcja pobiera odpowiednie tłumaczenie na podstawie locale i key. Obsługuje również formatowanie ciągów, aby wstawiać dynamiczne wartości (takie jak product_id).
\n
• Dynamiczne komunikaty o błędach: HTTPException jest teraz zgłaszany z komunikatem detail, który jest dynamicznie generowany przy użyciu funkcji get_translation.
\n

Gdy klient żąda /products/101?locale=fr, otrzyma komunikat o błędzie w języku francuskim (jeśli tłumaczenie jest dostępne). Gdy żąda /products/-1?locale=es, otrzyma komunikat o błędzie dotyczący ujemnego ID w języku hiszpańskim (jeśli dostępny). Gdy żąda /products/200?locale=xx (lokalizacja bez tłumaczeń), otrzyma komunikat `Translation missing`.

Najlepsze praktyki w obsłudze błędów

Oto kilka najlepszych praktyk, o których należy pamiętać podczas implementacji obsługi błędów w FastAPI:

\n
• Używaj niestandardowych wyjątków: Zdefiniuj niestandardowe klasy wyjątków, aby reprezentować specyficzne warunki błędów w Twojej aplikacji.
\n
• Dostarczaj informacyjne komunikaty o błędach: Dołącz jasne i zwięzłe komunikaty o błędach, które pomogą klientom zrozumieć przyczynę błędu.
\n
• Używaj odpowiednich kodów statusu HTTP: Zwracaj kody statusu HTTP, które dokładnie odzwierciedlają naturę błędu. Na przykład, użyj 400 (Bad Request) dla nieprawidłowych danych wejściowych, 404 (Not Found) dla brakujących zasobów i 500 (Internal Server Error) dla nieoczekiwanych błędów.
\n
• Unikaj ujawniania wrażliwych informacji: Uważaj, aby nie ujawniać wrażliwych informacji, takich jak dane uwierzytelniające do bazy danych lub klucze API w komunikatach o błędach.
\n
• Loguj błędy: Loguj szczegółowe informacje o błędach w celach debugowania i monitorowania. Użyj biblioteki logowania, takiej jak wbudowany w Pythonie moduł logging.
\n
• Scentralizuj logikę obsługi błędów: Skonsoliduj logikę obsługi błędów w jednym miejscu, na przykład w niestandardowych obsługa wyjątków lub middleware.
\n
• Testuj obsługę błędów: Napisz testy jednostkowe, aby upewnić się, że Twoja logika obsługi błędów działa poprawnie.
\n
• Rozważ użycie dedykowanej usługi śledzenia błędów: W środowiskach produkcyjnych rozważ użycie dedykowanej usługi śledzenia błędów, takiej jak Sentry lub Rollbar, do monitorowania i analizowania błędów. Narzędzia te mogą dostarczyć cennych informacji na temat stanu Twojej aplikacji i pomóc szybko zidentyfikować i rozwiązać problemy.
\n

Wnioski

Niestandardowe obsługi wyjątków to potężne narzędzie do budowania solidnych i przyjaznych dla użytkownika API w FastAPI. Definiując niestandardowe klasy wyjątków i obsługi, możesz elegancko zarządzać błędami, dostarczać klientom informacyjne odpowiedzi oraz poprawiać ogólną niezawodność i łatwość utrzymania swojej aplikacji. Połączenie niestandardowych wyjątków, wyjątków HTTP i wykorzystanie zasad i18n, gdy ma to zastosowanie, przygotowuje Twoje API na globalny sukces.

Pamiętaj, aby wziąć pod uwagę doświadczenie użytkownika podczas projektowania strategii obsługi błędów. Dostarczaj jasne i zwięzłe komunikaty o błędach, które pomogą użytkownikom zrozumieć problem i sposób jego rozwiązania. Skuteczna obsługa błędów to podstawa budowania wysokiej jakości API, które spełniają potrzeby zróżnicowanej, globalnej publiczności.